Developer Documentation

QuickTime 4 API Documentation

QuickTime For Windows Programmers

| Previous | Chapter Contents | Chapter Top | Roadmap | Next |

Data Conversion

The utility functions described in this section map between data formats used by Windows and those used by QuickTime.

NativeEventToMacEvent

NativeEventToMacEvent converts Win32 messages to Macintosh events.

long NativeEventToMacEvent(void *nativeEvent, EventRecord *macEvent);
macEvent
A pointer to Macintosh EventRecord structure to be filled in.

DISCUSSION

Use this function from a WndProc to convert a message structure to an equivalent Macintosh event record. NativeEventToMacEvent translates Win32 message types into Macintosh event types and fills in the various other EventRecord fields based on the source Win32 MSG . Typically, when your application hosts a movie controller, it should call NativeEventToMacEvent to translate a Win32 MSG to an EventRecord , and then pass the resulting EventRecord to MCIsPlayerEvent for processing. This function returns noErr if the translation succeeded. You should never call this function and then exit early from your WndProc without calling DefWindowProc or returning an appropriate result code from your WndProc .

GetPictFromDIB

You use the GetPictFromDIB function to create a QuickDraw PicHandle from a Windows HANDLE to a Device Independent Bitmap (DIB).

PicHandle GetPictFromDIB (void *h);
h
A Windows HANDLE to a DIB

DESCRIPTION

The GetPictFromDIB function returns a PicHandle when passed a Windows HANDLE to a DIB . The caller is responsible for releasing the memory of the PicHandle . You call the function KillPicture to release the memory of PicHandle .

Note that this function does not work for HBITMAP .

The format of the DIB handle is the same as returned by GetClipboardData with CF_DIB .

GetDIBFromPict

You use the GetDIBFromPict function to create a Windows HANDLE to a Device Independent Bitmap (DIB) from a QuickDraw PicHandle.

void *GetDIBFromPict (PicHandle hPict);
hPict
Specifies a handle to a Mac OS-style PICT .

function result
A Windows HANDLE to a DIB. This is not a Mac OS handle.

DESCRIPTION

The GetDIBFromPict function returns a global Windows HANDLE to a DIB when passed a PicHandle. To get a pointer to the data, you need to call GlobalLock(winHandle), which returns the pointer. The caller is responsible for releasing the memory of the Windows HANDLE. You call the function GlobalFree to release the memory of the DIB handle.

Note: Prior to QuickTime 4, it was possible to obtain a pointer to the data by simply dereferencing the Windows HANDLE (*winHandle). This was not correct, but it happened to work. You must call GlobalLock(winHandle) to obtain the pointer from the DIB handle in QuickTime 4 or later, which is also the correct approach for earlier versions of QuickTime.

Note also that the DIB handle is not the same as HBITMAP .

NativeRegionToMacRegion

The NativeRegionToMacRegion function converts a Windows HRGN to a Macintosh region handle.

RgnHandle NativeRegionToMacRegion(void *nativeRegion)
nativeRegion
A Windows HRGN .

function result
A Macintosh region handle.

DISCUSSION

The RgnHandle should be disposed of by the caller.

MacRegionToNativeRegion

The MacRegionToNativeRegion function converts a Macintosh region handle to a Windows HRGN .

void *MacRegionToNativeRegion(RgnHandle macRegion);
macRegion
A Macintosh region handle.

function result
A Windows HRGN .

FSSpecToNativePathName

The FSSpecToNativePathName function extracts the native pathname from an FSSpec .

OSErr FSSpecToNativePathName(FSSpec *inFile, char *outName,
                                          unsigned long outLen, long flags);
inFile
Contains a pointer to a FSSpec .

outName
Contains a pointer to a buffer to hold a C string.

outLen
Specifies the maximum size of the buffer in bytes, including thestring terminator.

flags
Contains flags that control the conversion. The following flags are valid:

kFullNativePath
This indicates that the full pathname should be returned.

kFileNameOnly
Only the part of the pathname corresponding to the file should be returned. This might be useful to return a string for a window's title.

kDirectoryPathOnly
The full pathname up to and including the enclosing directory but not the filename should be returned. This can be useful to get a path for the enclosing directory that might be used to find related files in the same directory.

As an example, consider the following Windows full path:

D:\Media\My Movies\Really Cool Movies\Tasty Fish.mov

If you have an FSSpec for this path, you can extract either the whole path or portions of the path using one of the above flags. For the above path and each flag, the resulting strings are:

Using kFullNativePath gives

D:\Media\My Movies\Really Cool Movies\Tasty Fish.mov

Using kFileNameOnly gives

Tasty Fish.mov

Using kDirectoryPathOnly gives

D:\Media\My Movies\Really Cool Movies

DISCUSSION

Sometimes, developers may need to convert a FSSpec returned by QuickTime APIs to a native pathname to be passed into the current operating system. The FSSpecToNativePathName function accepts an FSSpec and fills in the buffer pathname whose size is pathnameMaxBufferSize with the equivalent pathname string. This size must also include the size necessary to hold the string terminator.

NativePathNameToFSSpec

The NativePathNameToFSSpec function, given a native pathname, returns an FSSpec for that file.

OSErr NativePathNameToFSSpec(char *inName, FSSpec *outFile, long flags);
inName
Contains a pointer to the native pathname.

outFile
Contains a pointer to FSSpec .

flags
Contains flags that control the conversion.

DISCUSSION

Given a C string pathname from the operating system, this routine updates the FSSpec of outFile to describe the same file. There are no flags currently defined, so you should pass 0. NativePathNameToFSSpec returns noErr even if the file does not currently exist, and the resulting FSSpec is valid for creating the file.

Note: Earlier versions of this documentation incorrectly stated that if the file does not currently exist, the error fnfErr is returned. This is only true for QuickTime 4.0. QuickTime 4.01 and later (as well as all versions of QuickTime 3) return noErr even if the file does not currently exist.

QTMLGetCanonicalPathName

The QTMLGetCanonicalPathName routine takes a native file path and returns the one canonical path to that file.

OSErr QTMLGetCanonicalPathName(char *inName, char *outName,
                                          unsigned long outLen);
inName
Specifies the input path.

outName
Specifies where the routine puts the canonical path.

outLen
Specifies the length of the outName buffer, so that the routine knows not to write past the end of your buffer.

DISCUSSION

This routine takes a native file path and returns the one canonical path to that file.

Some of the tasks performed by this routine include:

For example, if you have a file with the following path

c:\Program Files\Some Product\test.mov

and the 8.3 path happens to be:

c:\PROGRA~1\SOMEPR~1\test.mov

you can pass any of the following paths to QTMLGetCanonicalPathName

c:\Some other folder\..\program FILES\another program\..\somepr~1\TeSt.MoV
 C:\proGra~1\Some product\..\SOMEPR~1\..\..\program files\some product\test.mov
 C:\PROGRA~1\SOMEPR~1\TEST.MOV

and it will always return

c:\Program Files\Some Product\test.mov

DISCUSSION

There is a one-to-one mapping between canonical pathnames and files. In other words, you can determine if two paths point to the same file by canonicalizing both paths, and then doing a string compare.

This routine also works for universal naming convention (UNC) paths. These paths are of the form:

\\my_server\shared_folder\another folder\test.mov

QTMLGetVolumeRootPath

The QTMLGetVolumeRootPath routine takes a Windows path and returns that portion of it which points to the volume root.

OSErr QTMLGetVolumeRootPath(char *fullPath, char * volumeRootPath, unsigned long
                                          volumeRootLen);
fullPath
Specifies the path being passed in.

volumeRootPath
Specifies where this routine writes the volume root path.

volumeRootLen
Specifies the length of the volumeRootPath buffer, so the routine knows not to write past the end of your buffer.

DISCUSSION

This routine works in the following way. If you pass in

c:\some folder\test.mov

it will return c:\

and if you pass in

\\my_server\shared_folder\mystuff\test.mov

it will return

\\my_server\shared_folder\

This is useful when you need to call Windows routines, such as GetVolumeInformation , which take a volume root path as an argument.

© 1998 Apple Computer, Inc.

| Previous | Chapter Contents | Chapter Top | Roadmap | Next |